<!DOCTYPE HTML>
<html>
<head>
<title>文件对象 | AutoHotkey</title>
<meta name="description" content="The file object provides an interface for a file to perform actions, such as reading or writing data, or to retrieve or set values, such as length." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
<script type="text/javascript">$(function(){0<=window.navigator.userAgent.toLowerCase().indexOf("ucbrowser")&&CaoNiMaDeUc()})</script>
</head>
<body>

<h1>文件对象 <span class="ver">[AHK_L 42+]</span></h1>

<p>提供文件输入/输出的接口. <a href="../commands/FileOpen.htm">FileOpen()</a> 返回文件类型的对象.</p>

<h2 id="Members">对象成员</h2>
 <p>属性:</p>
 <ul>
   <li><a href="#Seek">Position / Pos</a>: 获取或设置文件指针的位置. 等同于 <code>Pos := File.Tell()</code> 或 <code>File.Seek(Distance)</code>.</li>
   <li><a href="#Length">Length</a>: 获取或设置文件的大小.</li>
   <li><a href="#AtEOF">AtEOF</a>: 获取一个非零值当文件指针到达文件的末尾时.</li>
   <li><a href="#Encoding">Encoding</a>: 获取或设置此文件对象使用的编码.</li>
   <li><a href="#Handle">__Handle</a>: 获取用于 DllCall() 的系统文件句柄.</li>
 </ul>
 <p>方法:</p>
 <ul>
   <li><a href="#Read">Read</a>: 从文件中读取字符串, 并向前移动文件指针(文本向右为前).</li>
   <li><a href="#Write">Write</a>: 写入字符串到文件并向前移动文件指针.</li>
   <li><a href="#ReadLine">ReadLine</a>: 从文件中读取一行文本并向前移动文件指针.</li>
   <li><a href="#WriteLine">WriteLine</a>: 根据打开文件时使用的标志(flags), 写入后面跟着 <code>`n</code> 或 <code>`r`n</code> 的字符串. 向前移动文件指针.</li>
   <li><a href="#ReadNum">Read<em>NumType</em></a>: 从文件中读取指定类型的数据并向前移动文件指针.</li>
   <li><a href="#WriteNum">Write<em>NumType</em></a>: 写入指定类型的数据到文件并向前移动文件指针.</li>
   <li><a href="#RawRead">RawRead</a>: 从文件读取原始的二进制数据到内存并向前移动文件指针.</li>
   <li><a href="#RawWrite">RawWrite</a>: 写入原始的二进制数据到文件并向前移动文件指针.</li>
   <li><a href="#Seek">Seek</a>: 移动文件指针. 如果第二个参数被省略, 等同于 <code>File.Pos := Distance</code>.</li>
   <li><a href="#Tell">Tell</a>: 返回文件指针的当前位置. 等同于 <code>Pos := File.Pos</code>.</li>
   <li><a href="#Close">Close</a>: 关闭文件, 将缓存中的所有数据写入磁盘并释放共享锁定.</li>
 </ul>

<div class="methodShort" id="Read"><h2>Read</h2>
<p>从文件读取字符串并使文件指针向前移动.</p>
<pre class="Syntax">String := File.<span class="func">Read</span>(<span class="optional">Characters</span>)</pre>
<dl>
  <dt>Characters</dt>
  <dd>需读取的最大字符数. 如果省略, 则读取文件的剩余部分并作为单个字符串返回. 如果 File 对象创建于非搜寻设备(例如控制台缓冲区或管道) 的句柄, 省略此参数可能引起执行方法失败或仅返回当前可用的数据.</dd>
</dl>
  <p><strong>返回</strong> 字符串.</p>
</div>

<div class="methodShort" id="Write"><h2>Write</h2>
<p>写入字符串到文件并使文件指针向前移动.</p>
<pre class="Syntax">File.<span class="func">Write</span>(String)</pre>
<dl>
    <dt>String</dt>
  <dd>要写入的字符串.</dd>
</dl>
  <p><strong>返回</strong> 写入的字节数(不是字符数).</p>
</div>

<div class="methodShort" id="ReadLine"><h2>ReadLine</h2>
<p>从文件中读取一行文本并使文件指针向前移动.</p>
<pre class="Syntax">TextLine := File.<span class="func">ReadLine</span>()</pre>
<p><strong>返回</strong> 一行文本.  其中可能包括  <code>`n</code>, <code>`r`n</code> 或 <code>`r</code> 取决于文件和打开文件时使用的 EOL 标志.</p>
<p>可以读取长达 65,534 个字符的行. 如果一个行的长度超过这个长度, 则该行的其余部分将通过对此方法的后续调用返回.</p></div>

<div class="methodShort" id="WriteLine"><h2>WriteLine</h2>
<p>根据打开文件时使用的标志(flags), 写入后面跟着 <code>`n</code> 或 <code>`r`n</code> 的字符串. 向前移动文件指针.</p>
<pre class="Syntax">File.<span class="func">WriteLine</span>(<span class="optional">String</span>)</pre>
<dl>
  <dt>String</dt>
  <dd>可选的字符串.</dd>
</dl>
<p><strong>返回</strong> 写入的字节数(不是字符数).</p>
</div>

<div class="methodShort" id="ReadNum"><h2>Read<i>NumType</i></h2>
<p>从文件中读取指定类型的数据并使文件指针向前移动.</p>
<pre class="Syntax">Num := File.Read<i>NumType</i>()</pre>
<p><em>NumType</em> 可以是 UInt, Int, Int64, Short, UShort, Char, UChar, Double 或 Float. 这些类型名称与 <a href="../commands/DllCall.htm#types">DllCall()</a> 具有相同的含义.</p>
<p><strong>返回</strong> 数字, 如果失败则返回空字符串.</p>
<p>如果使用 Try 语句且没有读取任何字节时将抛出异常. 但是, 如果读取到任何字节则不会抛出异常, 即使 <i>NumType</i> 的设定值大于读取的字节数. 不足位用 0 填充.</p></div>

<div class="methodShort" id="WriteNum"><h2>Write<i>NumType</i></h2>
<p>写入指定类型的数据到文件并使文件指针向前移动.</p>
<pre class="Syntax">File.Write<i>NumType</i>(Num)</pre>
<dl>
  <dt>Num</dt>
  <dd>写入的数字.</dd>
</dl>
<p><em>NumType</em> 可以是 UInt, Int, Int64, Short, UShort, Char, UChar, Double 或 Float. 这些类型名称与 <a href="../commands/DllCall.htm#types">DllCall()</a> 具有相同的含义.</p>
<p><strong>返回</strong> 写入的字节数. 例如, 写入成功时 WriteUInt 返回 4.</p>
</div>

<div class="methodShort" id="RawRead"><h2>RawRead</h2>
<p>从文件读取原始的二进制数据到内存并向前移动文件指针.</p>
<pre class="Syntax">File.<span class="func">RawRead</span>(VarOrAddress, Bytes)</pre>
<dl>
  <dt>VarOrAddress</dt>
  <dd>用来保存复制出来的数据的变量或内存地址. 用法类似于 <a href="../commands/NumGet.htm">NumGet</a>.</dd>
  <dt>Bytes</dt>
  <dd>需读取的最大字节数.</dd>
</dl>
<p><strong>返回</strong> 读取的字节数.</p>
<p>如果使用 Try 语句, 且 <em>Bytes</em> 不为零, 但是没有读取到字节, 则抛出异常. 如果有需要, 可使用 <a href="#AtEOF">AtEOF</a> 来避免这种情况.</p></div>

<div class="methodShort" id="RawWrite"><h2>RawWrite</h2>
<p>写入原始的二进制数据到文件并向前移动文件指针.</p>
<pre class="Syntax">File.<span class="func">RawWrite</span>(VarOrAddress, Bytes)</pre>
<dl>
  <dt>VarOrAddress</dt>
  <dd>包含数据的变量或内存中的数据地址. 用法类似于 <a href="../commands/NumPut.htm">NumPut()</a>. 如果指定了变量, 则必要时会自动扩展.</dd>
  <dt>Bytes</dt>
  <dd>需写入的字节数.</dd>
</dl>
<p><strong>返回</strong> 写入的字节数.</p>
</div>

<div class="methodShort" id="Seek"><h2>Seek</h2>
<p>移动文件指针.</p>
<pre class="Syntax">
File.<span class="func">Seek</span>(Distance <span class="optional">, Origin := 0</span>)
File.Position := Distance
File.Pos := Distance
</pre>
<dl>
  <dt>Distance</dt>
<dd>需移动的距离, 单位为字节. 较小的值更接近文件的开始处.</dd>
  <dt>Origin</dt>
  <dd><p>文件指针开始移动的起点. 必须为下列值的其中一个:</p>
    <ul>
      <li>0(SEEK_SET): 文件的开始处. <i>Distance</i> 必须为零或更大.</li>
      <li>1(SEEK_CUR): 文件指针的当前位置.</li>
      <li>2(SEEK_END): 文件的末尾. <i>Distance</i> 通常应该为负数.</li>
    </ul>
    <p>如果省略, 当 Distance 为负数时 <i>Origin</i> 为 SEEK_END, 而其他情况时为 SEEK_SET.</p></dd>
</dl>
<p><strong>返回</strong> 非零值在成功时, 否则为零.</p>
</div>

<div class="methodShort" id="Tell"><h2>Tell</h2>
<p>返回文件指针的当前位置, 其中 0 是文件的开始.</p>
<pre class="Syntax">
Pos := File.<span class="func">Tell</span>()
Pos := File.Position
Pos := File.Pos
</pre>
</div>

<div class="methodShort" id="Length"><h2>Length</h2>
<p>获取或设置文件的大小.</p>
<pre class="Syntax">FileSize := File.Length</pre>
<pre class="Syntax">File.Length := NewSize</pre>
<p><em>FileSize</em> 和 <em>NewSize</em> 是文件的大小, 单位为字节.</p>
<p>此属性应该仅用于真实的文件. 如果 File 对象创建于管道的句柄, 那么它可能返回管道内部缓冲区中当前可能数据的数目, 但不能保证一定如此.</p></div>

<div class="methodShort" id="AtEOF"><h2>AtEOF</h2>
  <p>当文件指针到达文件末尾时, 返回非零值, 否则为零.</p>
<pre class="Syntax">IsAtEOF := File.AtEOF</pre>
<p>此属性应该仅用于真实的文件. 如果 File 对象创建于非搜寻设备(例如控制台缓冲区或管道) 的句柄, 那么返回的值可能没有意义, 因为这些设备逻辑上没有"文件末尾".</p></div>

<div class="methodShort" id="Close"><h2>Close</h2>
<p>关闭文件, 把缓冲区的数据写入磁盘并释放共享锁定.</p>
<pre class="Syntax">File.<span class="func">Close</span>()</pre>
<p>尽管当对象释放时文件会自动关闭, 不过建议尽快关闭文件.</p></div>

<div class="methodShort" id="Encoding"><h2>Encoding</h2>
<p>获取或设置此文件对象使用的编码.</p>
<pre class="Syntax">RetrievedEncoding := File.Encoding</pre>
<pre class="Syntax">File.Encoding := NewEncoding</pre>
  <p><em>RetrievedEncoding</em> 和 <em>NewEncoding</em> 是一个代表代码页标识符的数字(请参阅 <a href="http://msdn.microsoft.com/en-us/library/dd317756.aspx">MSDN</a>) 或以下字符串之一:</p>
  <ul>
	<li><code>UTF-8</code>: Unicode UTF-8, 相当于 CP65001.</li>
	<li>带小端字节顺序标识的 Unicode UTF-16 等效于 CP1200.</li>
	<li><code>CP<i>nnn</i></code>: 带数字的标识符 <i>nnn</i> 的代码页.</li>
  </ul>
  <p><em>RetrievedEncoding</em> 不会返回带 <code>-RAW</code> 后缀的值, 不论文件如何被打开或是否包含字节顺序标识(BOM). 设置 <em>NewEncoding</em> 不会增加或移除 BOM, 因为 BOM 通常在文件建立时就被写入其中.</p>
  <p><span class="ver">[v1.1.15.04+]</span>: 设置 <em>NewEncoding</em> 为 <code>UTF-8-RAW</code> 或 <code>UTF-16-RAW</code> 合法, 但 <code>-RAW</code> 后缀将被忽略. 而之前的版本中, <code>UTF-8-RAW</code> 及 <code>UTF-16-RAW</code> 如同非法的 8 位编码, 导致所有非 ASCII 字符被丢弃, 不过这只会影响 <code>File.Encoding</code>, 而不会影响 <a href="../commands/FileOpen.htm">FileOpen()</a>.</p>
</div>

<div class="methodShort" id="Handle"><h2>__Handle</h2>
  <p>返回用于 DllCall() 的系统文件句柄. 请参阅 <a href="http://msdn.microsoft.com/en-us/library/aa363858.aspx">CreateFile</a>.</p>
<pre class="Syntax">File.__Handle</pre>
<p>文件对象使用内部缓冲区读取或写入. 如果数据已经被写入对象的内部缓冲区, 则在返回句柄前会确保把数据写入磁盘. 如果缓冲区中包含从文件读取的数据, 则会把数据丢弃且文件指针的实际位置被重设为由 <code>File.Pos</code> 表示的逻辑位置.</p></div>

</body>
</html>